MacOS Installation Guide for Stirling PDF

Stirling PDF for Mac is available as a native desktop application or can run as a server using the JAR file.

Desktop Application (Recommended)

Native Mac desktop app with all PDF tools available.

What You Get

• ✅ Native macOS application - Optimized for both Apple Silicon and Intel Macs
• ✅ Sign in to start - Choose Stirling Cloud or your self-hosted server on launch (required before using tools)
• ✅ Processes files locally after login - Most tools run offline once signed in
• ✅ Stirling Cloud login is offline-only today - SaaS sign-in keeps processing on your Mac; optional cloud assists for advanced tasks are planned for a future release
• ✅ All features included - Every PDF tool available
• ✅ Better performance - Native speed on M1/M2/M3 chips
• ✅ No external browser needed - Uses the built-in window
• ✅ Menu bar integration - Feels like a native Mac app

Installation Steps

1. Download the right version for your Mac:

Chip Type	Download Link
Apple Silicon (M1/M2/M3)	Download for Apple Silicon
Intel processors	Download for Intel

Not sure which chip you have?

• Click the Apple menu → "About This Mac"
• Look at "Chip" or "Processor"
• If it says "M1", "M2", or "M3" → Use Apple Silicon version
• If it says "Intel" → Use Intel version

2. Install the application:

1. Open the downloaded .dmg file
2. Drag Stirling PDF to your Applications folder

3. First-time launch (Security):

macOS will block the app on first launch because it's not from the App Store:

To allow Stirling PDF:

1. Open System Settings → Privacy & Security
2. Scroll down to the Security section
3. Click "Open Anyway" next to the Stirling PDF message
4. Enter your password if prompted
5. Go back to Applications and launch Stirling PDF again

The app will now open normally every time!

Using the Desktop App

1. Launch Stirling PDF
2. Sign in with your Stirling Cloud account or enter the URL for your self-hosted server.
3. After login, use the in-app interface to upload or drag-and-drop files into the window.

Making Stirling PDF your default PDF viewer:

1. Right-click (or Control+click) any PDF file
2. Select "Get Info"
3. Under "Open with", choose Stirling PDF
4. Click "Change All" to apply to all PDFs
5. Confirm when prompted

Benefits of desktop app:

• Files stay on your Mac (not in browser storage)
• Work without internet connection
• Native performance (especially on Apple Silicon)
• Unlimited file storage
• Menu bar integration
• macOS gestures and features work

Server Version (For Hosting and Sharing)

Want to host Stirling PDF on a Mac server for multiple users? Use the JAR file version.

Prerequisites

Install Java 21 (required for server version):

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Java 21
brew install openjdk@21

# Add to your PATH (add to ~/.zshrc to make permanent)
export PATH="/usr/local/opt/openjdk@21/bin:$PATH"

JAR Downloads

Stirling PDF comes in three different JAR files:

Stirling-PDF-with-login.jar (Recommended - Full Features):

• Download: Stirling-PDF-with-login.jar
• Bundles frontend UI + backend server in one file
• Includes authentication and additional features - requires user login (default credentials: admin / stirling)
• Recommended for all users - personal, shared, or enterprise deployments

Stirling-PDF.jar (Plain JAR - Basic Features):

• Download: Stirling-PDF.jar
• Bundles frontend UI + backend server in one file
• Basic version - no authentication, core features only
• Only use if you require no login at all and don't mind missing certain features

Stirling-PDF-server.jar (Backend Only - Advanced):

• Download: Stirling-PDF-server.jar
• Backend server only (no bundled UI)
• No authentication - API access only
• For desktop app backend, custom frontend, or API integrations

Running the Server

1. Download your preferred JAR file (see above)

2. Open Terminal and navigate to the download folder:

   cd ~/Downloads  # Or wherever you saved the JAR

3. Run Stirling PDF:

   java -jar Stirling-PDF.jar

4. Access via browser at http://localhost:8080

5. Share with others on your network at http://your-mac-ip:8080

Creating a Convenience Script

For easier launching, create a startup script:

1. Create the script:

   nano ~/run-stirling.sh

2. Add these contents:

   #!/bin/bash
   cd ~/Downloads  # Change to where your JAR is located
   java -jar Stirling-PDF.jar

3. Save and exit (Ctrl+X, then Y, then Enter)

4. Make it executable:

   chmod +x ~/run-stirling.sh

5. Run anytime with:

   ~/run-stirling.sh

Optional Dependencies

Install these via Homebrew to enable additional features like advanced document conversion or PDF compression:

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies as needed
brew install openjdk@21          # Required
brew install qpdf                # PDF compression
brew install --cask libreoffice  # Document conversion
brew install tesseract           # OCR functionality
brew install tesseract-lang      # Additional OCR languages
brew install poppler             # PDF to HTML conversion
pip3 install weasyprint          # URL to PDF conversion
pip3 install unoserver           # File to PDF conversion

For Tesseract OCR, add to config/settings.yml (generated once you first run the jar):

system:
  tessdataDir: /usr/local/share/tessdata

Quick Troubleshooting

• Java not found? Add to ~/.zshrc:

  export PATH="/usr/local/opt/openjdk@21/bin:$PATH"
• Verify installations with: [command] --version (e.g., java --version)
• LibreOffice issues? Ensure no LibreOffice processes are running
• Need help? Visit GitHub Issues

Starting unoserver alongside Stirling PDF

To ensure that unoserver is running alongside Stirling PDF, you need to start it with the following command:

unoserver --port 2003 --interface 0.0.0.0

You can add this command to your startup script or systemd service file to ensure it starts automatically with Stirling PDF.